The Run-Time Environment (IM: XOv)

Inside Macintosh: QuickDraw GX Programmer's Overview / Part 1 - Getting Started With QuickDraw GX: Chapter 1 - An Introduction to QuickDraw GX

The Run-Time Environment
QuickDraw GX provides services for your application during run time that are not necessarily graphics-related. For example, QuickDraw GX provides error-handling mechanisms for your application.
The next few sections discuss the two versions of QuickDraw GX and some of the run-time services they provide.

Versions of QuickDraw GX
There are two versions of QuickDraw GX:

The debugging version is the version you should be using while developing your application. This version provides extensive error-handling and validation facilities you can use while debugging and optimizing your application. It requires more memory and runs more slowly than the non-debugging version.
The non-debugging version is the publicly released version that your application's users will be running. This version has much less extensive error handling, which makes it smaller and faster than the debugging version. It is intended for use with fully debugged applications.

These two versions are similar in many ways. With very few exceptions, they support the same data types and functions, and, during runtime, they both create a run time environment that includes a new memory management system, as described in the next section.
The two versions differ mostly in debugging support--specifically, how they deal with error situations that your application causes. The section, "Error Handling," on page 32 describes the QuickDraw GX error-handling system and describes some of the differences between the way the debugging and non-debugging versions handle errors.

Memory
The Macintosh Memory Manager divides memory into three broad sections: system memory, temporary memory, and application memory. When your application is running, the Macintosh Memory Manager devotes a partition
of application memory exclusively to your application. Within this partition
is your application stack and your application heap. Normally, when your application allocates a block of memory, it uses a Macintosh Memory Manager function (such as NewHandle) and the Macintosh Memory Manager allocates the block of memory in your application heap.
QuickDraw GX provides a new memory management scheme, which cooperates with, but works independently of, the Macintosh Memory Manager. QuickDraw GX allocates its own memory out of its own application memory section. Before your application can use QuickDraw GX, you must create a special heap just for storing your QuickDraw GX objects. This heap is called your graphics client heap.
You can use the Macintosh Memory Manager to allocate memory for your graphics client heap; in this case, your graphics client heap exists within your application heap. More commonly, however, you request QuickDraw GX to allocate your graphics client heap out of temporary memory. In this way, QuickDraw GX has complete control over the memory location of your application's QuickDraw GX objects.
Figure 1-10 shows the typical organization of Macintosh memory, QuickDraw GX memory, your application partition, and your graphics
client heap.
Figure 1-10 QuickDraw GX memory organization

QuickDraw GX can move your objects out of your graphics client heap--
for example, to store them on the memory of a graphics accelerator card. QuickDraw GX can also automatically increase the size of your graphics client heap should you need more memory and there is more memory available.
Sometimes, of course, more memory won't be available and your application will receive an out-of-memory error in response to calling a QuickDraw GX function. The next section, "Error Handling," discusses the QuickDraw GX error-handling system that you can use to respond to an out-of-memory error condition.
However, it's usually best to prevent out-of-memory errors before they occur. Your application can do many things to limit the amount of graphics memory needed: object sharing is one example; disposing of objects that your applica-
tion no longer needs is another.

Error Handling
QuickDraw GX uses two different error-handling schemes:

The graphics and typography parts of QuickDraw GX use a three-level
error, warning, and notice system for reporting error conditions to your application.
The printing part of QuickDraw GX uses an error system and a polling method similar to that used by the Macintosh Printing Manager.

This following two sections introduce these error-handling schemes in
more detail.

Graphics and Typography Errors
Whenever your application makes a call to a QuickDraw GX function, an error condition may result. Actually, the execution of a QuickDraw GX graphics
or typography function may result in the generation of one of three levels
of errors:

A true error indicates a severe problem. QuickDraw GX only posts an error when the function is unable to execute.
A warning is slightly less severe. QuickDraw GX posts a warning
when the function completes, but may have provided an incorrect or
unexpected result.
A notice is the least severe. QuickDraw GX posts a notice if the function completed, but performed unnecessary or redundant actions.

The debugging versions of the QuickDraw GX system extension detects and posts many more errors, warnings, and notices than the non-debugging version. In fact, the non-debugging version posts a limited number of errors and warnings and posts no notices at all.
QuickDraw GX does not return errors, warnings, and notices as function results. Instead, it posts them--stores them in a location accessible through function calls. There is a QuickDraw GX function your application can call to determine whether an error has occurred, or you can install an error-handling function that QuickDraw GX calls whenever an error condition occurs.
When a QuickDraw GX graphics or typography function fails, it returns nil as its function result.

Printing Errors
Typically, when a printing-related error occurs, QuickDraw GX places the error directly in the job object involved. After you call a QuickDraw GX printing function, your application can call another function which examines the job object to determine whether any errors were stored in it. This process is called polling for errors. You can poll for errors after each printing function call, or after groups of calls.
As with graphics and typography, there is a QuickDraw GX printing function your application can call to determine whether an error has occurred, or you can install an error-handling function that QuickDraw GX calls whenever an error condition occurs.
Also, there are some QuickDraw GX printing functions that return an error code as the function result.